<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<link rel="shortcut icon" type="image/x-icon" href="favicon.ico"/>
<title>DynamoRIO API: IA-32/AMD64 Disassembly Library</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">DynamoRIO API
   </div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.1.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('page_standalone.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">IA-32/AMD64 Disassembly Library </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>DynamoRIO can be used as a standalone library for IA-32/AMD64 disassembly, decoding, encoding, and general instruction manipulation, independently of controlling a target application. When used in this way, all aspects of DynamoRIO's API routines that apply to instrumentation or application control are not applicable; however, the full, rich instruction set API is enabled. For further information on the instruction set API see the following sections of the Code Manipulation API:</p>
<ul>
<li><a class="el" href="API_BT.html#sec_IR">Instruction Representation</a></li>
<li><a class="el" href="API_BT.html#sec_decode">Decoding and Encoding</a></li>
</ul>
<h1><a class="anchor" id="sec_standalone"></a>
Using DynamoRIO as a Standalone Library</h1>
<p>DynamoRIO can be used as a regular third-party library for a standalone application (instead of a client that operates on a target program). Two options are provided: using the regular DynamoRIO shared library, or using a special static library <code>drdecode</code>. The shared library provides not only decoding routines but also cross-platform resources such as file manipulation.</p>
<p>When using the DynamoRIO shared library, this initialization routine must be called prior to using any API routines:</p>
<div class="fragment"><div class="line"> <a class="code" href="dr__tools_8h.html#af63184f56cc0508e2840f64e84b1c48d">dr_standalone_init</a>() </div>
</div><!-- fragment --><p>This routine returns a dummy context that can be passed to API routines.</p>
<p>When using <code>drdecode</code>, the special context <code>GLOBAL_DCONTEXT</code> should be used whenever a context is required. The <code>drdecode</code> library does not require initialization.</p>
<p>Neither the context returned by <a class="el" href="dr__tools_8h.html#af63184f56cc0508e2840f64e84b1c48d">dr_standalone_init()</a> nor <code>GLOBAL_DCONTEXT</code> can be used as the drcontext for a thread running under DynamoRIO control! It is only for standalone programs that wish to use DynamoRIO as a library of routines for IA-32 instruction manipulation or other purposes.</p>
<p>In standalone mode, the <a class="el" href="dr__ir__utils_8h.html#adf9a4f63eafc7f9725f7d5bf1725ab5c">set_x86_mode()</a> routine operates globally rather than per-thread.</p>
<p>Runtime options are ignored in standalone mode. Disassembly style can be controlled via <a class="el" href="dr__ir__utils_8h.html#a3082c5db55039c72ae30e3276f622aae">disassemble_set_syntax()</a>. The processor to use will not be automatically set and will be assumed to be <code>VENDOR_INTEL</code>. Use <a class="el" href="dr__proc_8h.html#a5a9d6c28ef304d6b4f5e1a45fb9da996">proc_set_vendor()</a> to set to <code>VENDOR_AMD</code> instead.</p>
<p>Some DynamoRIO API routines are not supported in standalone mode. These include all event registration routines, module iteration, <a class="el" href="dr__tools_8h.html#a2c3a19a0dc146c1e5b6747e89bacfb55">dr_memory_protect()</a>, <a class="el" href="dr__tools_8h.html#ad444a204e7ca45f9965cfe973470375a">dr_messagebox()</a>, <a class="el" href="dr__tools_8h.html#a13217cc252506b06184c7c72adedf26c">dr_get_current_drcontext()</a>, <a class="el" href="dr__tools_8h.html#a3980d703cc13379a6b57396a7901b1d1">dr_get_thread_id()</a>, tls fields, <a class="el" href="dr__tools_8h.html#ac262422c1e5e487113176bd4193c387f">dr_thread_yield()</a>, <a class="el" href="dr__tools_8h.html#af154e498d8b185931ef970676cb65351">dr_sleep()</a>, client threads, suspending threads, itimers, register spilling and restoring, <a class="el" href="dr__ir__utils_8h.html#a9f612cf9d0ca2025b23d30b6f5bb0231">dr_redirect_execution()</a>, try/except, and code cache routines (e.g., <a class="el" href="dr__tools_8h.html#a7600cc31d68dc0e30ab91261d08836ed">dr_delete_fragment()</a> or flush routines).</p>
<p>When using the <code>drdecode</code> library, no API routines other than those involving decoding, encoding, disassembling, instruction lists, instructions, or operands are supported. The various compute_address routines can be used by manually filling in <code>dr_mcontext_t</code>, although far memory references will have their segment base ignored. Other API routines are simply not present in the static library. There is no separate set of headers for use with <code>drdecode</code>.</p>
<p>When using DynamoRIO's CMake support, use the configure_DynamoRIO_decoder() function to set up include directories and to link with <code>drdecode</code>. The next section describes how to link with the DynamoRIO shared library.</p>
<h2><a class="anchor" id="sec_relativize"></a>
Re-Relativization of Jumps and Calls</h2>
<p>When encoding a relative jump or call to a different location than it was decoded from while in standalone mode, a re-encode must be forced in order to work around an issue where DynamoRIO does not re-relativize the target:</p>
<div class="fragment"><div class="line"><a class="code" href="dr__ir__instr_8h.html#a76b3326d827b06a1d1d0bc3d20ba17a2">instr_set_raw_bits_valid</a>(instr, <span class="keyword">false</span>)</div>
</div><!-- fragment --><p>When not in standalone mode, all branches are mangled and thus this is never an issue. This should be fixed in a future release.</p>
<h1><a class="anchor" id="sec_standalone_shared"></a>
DynamoRIO Shared Library Issues</h1>
<p>Since the DynamoRIO library on Windows includes or forwards implementations of certain C library routines (see <a class="el" href="using.html#subsec_forwards">C library utilities</a>), standalone applications linking to both DynamoRIO and the C library may experience linker errors when building and floating point problems when running. To avoid these problems, explicitly list the C runtime library on the command line:</p>
<div class="fragment"><div class="line"> /link /nodefaultlib libcmt.lib dynamorio.lib </div>
</div><!-- fragment --><p>DynamoRIO writes to stderr and stdout using raw system calls, which can interfere with the buffering of library routines. When mixing use of printf or fprintf with DynamoRIO output (including not only <a class="el" href="dr__tools_8h.html#abad2eddb3786e3e909ff36da39b7e31e">dr_printf()</a> and <a class="el" href="dr__tools_8h.html#a1affb1a9f1c49c1959f1a01967a0a0d9">dr_fprintf()</a> but also passing STDOUT or STDERR to routines like <a class="el" href="dr__ir__utils_8h.html#a526fc9f23e78b5f1321891dc8f81b1b7">disassemble()</a>), you may need to flush between library printing and DynamoRIO printing (e.g., using fflush(stdout)) to ensure that the library output is visible.</p>
<p>The binary tracedump reader (<a class="el" href="API_samples.html#sec_ex8">Use of Standalone API</a>) is an example of use of DynamoRIO as a standalone library.</p>
<p>When building an application that uses DynamoRIO as a standalone library, follow the steps for <a class="el" href="using.html#sec_build">Building a Client</a> to include the header files and link with the DynamoRIO library, but omit the linker flags requesting no standard libraries or startup files. DynamoRIO's CMake support does this automatically via the configure_DynamoRIO_standalone() function. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer" style="float:none;text-align:center"><img border=0 src="favicon.png"> &nbsp;  DynamoRIO API version 5.0.0 --- Wed Sep 10 2014 21:36:44 &nbsp; <img border=0 src="favicon.png">
</small></address>
<!--END !GENERATE_TREEVIEW-->
</body>
</html>
